/*
 * Copyright (c) 2011 Obix Labs Limited
 * Redistribution and use in source and binary forms, 
 * with or without modification, are permitted provided 
 * that the following conditions are met:
 * 
 * 		Redistribution of source code must retain the above 
 * 		copyright notice, this list of conditions and the 
 * 		following disclaimer.
 *
 * 		Redistribution in binary form must reproduce the 
 * 		above copyright notice, this list of conditions 
 * 		and the following disclaimer in the documentation 
 * 		and/or other materials provided with the distribution.
 * 
 * 	THIS SOFTWARE IS PROVIDED "AS IS," WITHOUT A WARRANTY OF 
 * 	ANY KIND. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS 
 * 	AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, 
 * 	FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, 
 * 	ARE HEREBY EXCLUDED. OBIX LABS LIMITED ("Obix Labs") AND ITS 
 * 	LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE 
 * 	AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR 
 * 	ITS DERIVATIVES. IN NO EVENT WILL Obix Labs OR ITS LICENSORS BE 
 * 	LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, 
 * 	INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE 
 * 	DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF 
 * 	LIABILITY, ARISING OUT OF THE USE OF OR INABILITY TO USE THIS 
 * 	SOFTWARE, EVEN IF Obix Labs HAS BEEN ADVISED OF THE POSSIBILITY OF 
 * 	SUCH DAMAGES.
 */
package com.obixlabs.commons.util;

import com.obixlabs.commons.security.AbstractCharPresencePasswordRequirement;

/**
 * <P>
 * Defines the contract for a class that provides character data. This interface is intended
 * for client classes and applications which require character data, but which should not
 * have to deal with the intricacies of how such data is collected or generated. For an example of 
 * where this interface is used, see {@link AbstractCharPresencePasswordRequirement}.
 * </P>
 */
public interface CharacterSource
{
        /**
         * <P>
         * Returns the next available upper case character. 
         * </p> 
         * @return An upper case character.
         */
	char nextUpperCaseChar();

	       /**
         * <P>
         * Returns the next available lower case character. 
         * </p> 
         * @return A lower case character.
         */	
	char nextLowerCaseChar();

	/**
	 * Return the next available non alpha-numeric character. 
	 * @return A non alpha-numeric character.
	 */
	char nextNonAlphaNumericChar();

	/**
	 * Return the next available numeric character.
	 * @return A numeric character.
	 */
	char nextNumericChar();

	/**
	 * <p>
	 * Returns the next available character. This can be either alpha-numeric or non alpha-numeric.
	 * It could also be lower or upper case. Thus, the choice of character depends on the instance, or
	 * more specifically the rules defined in the implementation. 
	 *  </p>
	 *  
	 * @return A character.
	 */
	char nextChar();

	/**
	 * <p>
	 * Gets the next available alpha-numeric character. The choice of the type of character, i.e. 
	 * upper versus lower case, numeric or non-numeric, is left to the implementation. 
	 * </p>  
	 * 
	 * @return     An alpha-numeric character.
	 */
	char nextAlphaNumericChar();

	/**
	 * <p>
	 * Get the next available alphabetic character. The character can be either upper or lower case; the 
	 * choice of which is delegated to the implementation. 
	 * </p>
	 * 
	 * @return     An alphabetic character, the type of which is chosen by the instance.
	 */
	char nextAlphaChar();
}